Inside Macintosh: Programming With the Text Encoding Conversion Manager /

Chapter 2 - Basic Text Types Reference / Basic Text Functions

Obtaining Information From a Text Encoding Specification /

GetTextEncodingName

Returns the localized name for a specified text encoding.

OSStatus GetTextEncodingName (TextEncoding iEncoding,
                     TextEncodingNameSelector iNamePartSelector, 
                     RegionCode iPreferredRegion, 
                     TextEncoding iPreferredEncoding, 
                     ByteCount iOutputBufLen, 
                     ByteCount *oNameLength, 
                     RegionCode *oActualRegion, 
                     TextEncoding *oActualEncoding, 
                     TextPtr oEncodingName);

iEncoding

A text encoding specification whose name you want to obtain.

iNamePartSelector

The portion of the encoding name you want to obtain. See "Text Encoding Name Selector" (page 42) for a list of possible values.

iPreferredRegion

The preferred region to use for the name. You can specify a Mac OS region code (which also implies a language) for this parameter. If the function cannot return the name for the preferred region, it returns the name using a region code with the same language or in a default language (for example, English).

iPreferredEncoding

The preferred encoding to use for the name. For example, you might want the name returned encoded in ASCII, Mac OS Roman, or Shift-JIS. If the function cannot return the name using the preferred encoding, it returns the name using another encoding, such as Unicode or ASCII.

iOutputBufLen

The length in bytes of the output buffer that your application provides for the returned encoding name.

oNameLength

A pointer to a value of type ByteCount. On output, this parameter holds the actual length, in bytes, of the text encoding name. The value represents the full length of the name, which might be greater than the size of the output buffer, specified by the iOutputBufLen parameter. The length of the portion of the name actually contained in the output buffer is thus the smaller of oNameLength and iOutputBufLen.

oActualRegion

A pointer to a value of type RegionCode. On output, this parameter holds the actual region associated with the returned encoding name.

oActualEncoding

A pointer to a value of type TextEncoding. On output, this parameter holds the actual encoding associated with the returned encoding name.

oEncodingName

A pointer to a buffer you provide. On output, this parameter holds the text encoding name.

function result

A result code. For a list of possible result codes, see "Text Encoding Conversion Manager Result Codes" (page 43).

DISCUSSION

Names returnd by GetTextEncodingName (in the buffer referred to by oEncodingName) may contain parentheses and possibly other menu item metacharacters, and so cannot be used with AppendMenu or InsertMenuItem. They can, however, be used with SetMenuItemText. In addition to various resource and memory errors, this function can return the following result codes:

• kTextUnsupportedEncodingErr, which indicates that the encoding whose name you want to obtain is not supported.
• kTECMissingTableErr, which indicates the name resource associated with the encoding is missing.
• kTECTableFormatErr or kTECTableCheckSumErr, which indicates that the name resource associated with that encoding is invalid.

SEE ALSO

"Text Encoding Base" (page 31)